PHP SDK使用指南

本指南将会为您介绍如何使用PHP SDK接入您的项目。如果您想要了解游戏行业应该收集哪些数据以及如何收集，请查阅接入样例。如果您想获得API接口的详细说明，可以查看PHP SDK API文档。您可以在访问GitHub获取PHP SDK的源代码。

最新版本为：1.1.0

更新时间为：2019-09-12

1. 安装SDK

• 您可以从GitHub中获取 SDK 的源码，并集成到您的项目中。只需要将TaPhpSdk.php 放到你项目所在的目录即可。本SDK 兼容 PHP >5.5，部分功能依赖 curl 扩展。

• 您也可以使用 composer 集成

{ 
    "require": {
        "thinkinggame/ta-php-sdk": "v1.1.0"
    }
}

2. 初始化SDK

在程序中写入以下代码引入SDK：

<?php
require "TaPhpSdk.php";
?>

在引入SDK后，您需要获得SDK实例，可以获取三种不同的SDK实例，建议使用FileConsumer：

(1)FileConsumer：批量实时写本地文件，需要与LogBus搭配使用进行数据上传，建议使用，不支持多线程，生成实例时可通过传参调整文件切割规则。

<?php
//按默认大小 1024MB 切分一个文件
$ta = new ThinkingDataAnalytics(new FileConsumer("/log_dir"));

//设置文件切割的大小,单位是MB,默认是1024MB
//$ta = new ThinkingDataAnalytics(new FileConsumer("/log_dir", 512));

//按小时切分，文件名类似：log.日期-小时_数值（log.2019-09-12-15_0）
//数值是文件切分的索引
//$ta = new ThinkingDataAnalytics(new FileConsumer("/log_dir", 1024, true)); 
?>

传入的第一个参数为写入本地的文件夹地址，您只需将LogBus的监听文件夹地址设置为此处的地址，即可使用LogBus进行数据的监听上传。第二个参数是文件的切割大小，默认为1024MB，单位为MB。第三个参数设置是否按小时切分，默认为false，即不开启。

(2)BatchConsumer：批量实时地向TA服务器传输数据，不需要搭配传输工具，不建议在生产环境中使用，不支持多线程

<?php
$ta = new ThinkingDataAnalytics(new BatchConsumer("SERVER_URI","APP_ID"));
?>

SERVER_URI为传输数据的URL，APP_ID为您的项目的APP ID

如果您使用的是云服务，请输入以下URL:

http://receiver.ta.thinkingdata.cn/logagent

如果您使用的是私有化部署的版本，请输入以下URL:

http://数据采集地址/logagent

(3)DebugConsumer：逐条实时地向TA服务器传输数据，不需要搭配传输工具，如果数据出现错误，整条数据都将不会入库，并且返回详细的错误说明，不建议在生产环境中使用，不支持多线程

<?php
$ta = new ThinkingDataAnalytics(new DebugConsumer("SERVER_URI","APP_ID"));
?>

SERVER_URI为传输数据的URL，APP_ID为您的项目的APP ID

如果您使用的是云服务，请输入以下URL:

http://receiver.ta.thinkingdata.cn/logagent

如果您使用的是私有化部署的版本，请输入以下URL:

http://数据采集地址/logagent

3. 发送事件

在SDK初始化完成之后，您就可以调用track来上传事件，一般情况下，您可能需要上传十几到上百个不同的事件，如果您是第一次使用TA后台，我们推荐您先上传几个关键事件。

如果您对需要发送什么样的事件有疑惑，可以查看快速使用指南以及接入样例了解更多信息。

a) 发送事件

您可以调用track来上传事件，建议您根据先前梳理的文档来设置事件的属性以及发送信息的条件，此处以玩家付费作为范例：

<?php
// 用户在登录状态下的账号ID
$account_id = "ABC12345"; 

// 用户未登录时，可以使用产品自己生成的cookieId等唯一标识符来标注用户
$distinct_id = "SDIF21dEJWsI232IdSJ232d2332"; 

$properties = array();

//设置本条数据的时间，如不设置，则默认取当前时间，格式为"Y-m-d H:i:s"
$properties["#time"] = date("Y-m-d H:i:s",time());

//设置客户端IP，TA将会自动根据该IP地址解析其地理位置信息
$properties["#ip"] = "123.123.123.123";

//设置事件的其他属性
$properties["Product_Name"]:"月卡";
$properties["Price"]:30;
$properties["OrderId"]:"abc_123";

//传入参数分别为，访客ID，账号ID，事件名与事件属性
$ta->track($distinct_id,$account_id,"Payment",$properties);

//您可以只上传其中一个ID，SDK中其他需要上传用户ID的接口也可以只上传一个ID
//$ta->track($distinct_id,null,"Payment",$properties);
//$ta->track(null,$account_id,"Payment",$properties);
?>

注：为了保证访客ID与账号ID能够顺利进行绑定，如果您的游戏中会用到访客ID与账号ID，我们极力建议您同时上传这两个ID，否则将会出现账号无法匹配的情况，导致用户重复计算，具体的ID绑定规则可参考用户识别规则一章。

• 事件的名称只能以字母开头，可包含数字，字母和下划线“_”，长度最大为50个字符，对字母大小写不敏感。
• 事件的属性是一个关联数组，其中每个元素代表一个属性。
• 数组元素的Key值为属性的名称，为string类型，规定只能以字母开头，包含数字，字母和下划线“_”，长度最大为50个字符，对字母大小写不敏感。
• 数组元素的Value值为该属性的值，支持支持string、integer、float、boolean、DataTime

b) 设置公共事件属性

对于一些需要出现在所有事件中的属性属性，您可以调用register_public_properties来设置公共事件属性，我们推荐您在发送事件前，先设置公共事件属性。

<?php
$public_properties = array();
$public_properties["server_version"] ="1.2.3";
$public_properties["server_name"] = "A1001";
$ta->register_public_properties($public_properties);
?>

在调用register_public_properties设置完公共属性后，之后上传的所有事件中都会带有这些属性

• 公共事件属性同样也是一个关联数组，其中每个元素代表一个属性。
• 数组元素的Key值为属性的名称，为string类型，规定只能以字母开头，包含数字，字母和下划线“_”，长度最大为50个字符，对字母大小写不敏感。
• 数组元素的Value值为该属性的值，支持支持string、integer、float、boolean、DataTime

如果调用register_public_properties设置先前已设置过的公共事件属性，则会覆盖之前的属性值，以新设置的公共属性为准。如果公共事件属性和track上传事件中的某个属性的Key重复，则该事件的属性会覆盖公共事件属性，即以上传事件时的属性为准。

如果您想要清空所有公共事件属性，可以调用clear_public_properties。

<?php
$ta->clear_public_properties();
?>

3. 用户属性

TGA平台目前支持的用户属性设置接口为user_set、user_setOnce、user_add、user_del。

a) user_set

对于一般的用户属性，您可以调用user_set来进行设置，使用该接口上传的属性将会覆盖原有的属性值，如果之前不存在该用户属性，则会新建并写入该用户属性，属性类型与传入时的类型一致：

<?php
$properties = array();

//上传用户属性，新建属性"user_name"，值为"ABC"
$properties["user_name"] = "ABC";
$ta->user_set($distinct_id,$account_id,$properties);

//再次上传用户属性，此时"user_name"的值会被覆盖为"XYZ"
$properties["user_name"] = "XYZ";
$ta->user_set($distinct_id,$account_id,$properties);
?>

• user_set设置的用户属性是一个关联数组，其中每个元素代表一个属性。
• 数组元素的Key值为属性的名称，为string类型，规定只能以字母开头，包含数字，字母和下划线“_”，长度最大为50个字符，对字母大小写不敏感。
• 数组元素的Value值为该属性的值，支持支持string、integer、float、boolean、DataTime

b) user_setOnce

如果您要上传的用户属性只要设置一次，则可以调用user_setOnce来进行设置，当该属性之前已经有值的时候，将会忽略这条信息：

<?php
$properties = array();

//同样的，上传用户属性，新建属性"user_name"，值为"ABC"
$properties["user_name"] = "ABC";
$ta->user_setOnce($distinct_id,$account_id,$properties);

//再次上传用户属性，此时"user_name"已存在值，因此不进行修改，仍为"ABC"；"user_age"的值为18
$properties["user_name"] = "XYZ";
$properties["user_age"] = 18;
$ta->user_setOnce($distinct_id,$account_id,$properties);
?>

user_setOnce设置的用户属性类型及限制条件与user_set一致。

c) user_add

当您要上传数值型的属性时，您可以调用user_add来对该属性进行累加操作，如果该属性还未被设置，则会赋值0后再进行计算，可传入负值，等同于相减操作。

<?php

//上传用户属性，此时"total_revenue"的值为30,"level"的值为1
$properties = array();
$properties["total_revenue"] = 30;
$properties["level"] = 1;
$ta->user_add($distinct_id,$account_id,$properties);

//再次上传用户属性，此时"total_revenue"的值为90,"level"的值为1
$properties_other = array();
$properties_other["total_revenue"] = 60;
$ta->user_add($distinct_id,$account_id,$properties_other);
?>

user_add设置的用户属性类型及限制条件与user_set一致，但只对数值型的用户属性有效。

d) user_del

如果您要删除某个用户，可以调用user_del将这名用户删除，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到

<?php
$ta->user_del($distinct_id,$account_id);
?>

4. 其他操作

a) 立即提交数据

<?php
$ta->flush();
?>

立即提交数据到相应的接收器

b) 关闭sdk

<?php
$ta->close();
?>

关闭并退出sdk，请在关闭服务器前调用本接口，以避免缓存内的数据丢失

5. 相关预置属性

5.1 所有事件带有的预置属性

以下预置属性，是PHP SDK中所有事件（包括自动采集事件）都会带有的预置属性